import {Layout} from '../../src/Layout';
export default Layout;

import docs from 'docs:react-aria-components';
import vanillaDocs from 'docs:vanilla-starter/DateField';
import {DateField as VanillaDateField} from 'vanilla-starter/DateField';
import {DateField as TailwindDateField} from 'tailwind-starter/DateField';
import '../../tailwind/tailwind.css';
import Anatomy from '@react-aria/datepicker/docs/datefield-anatomy.svg';

export const tags = ['calendar', 'input'];
export const relatedPages = [{'title': 'useDateField', 'url': 'DateField/useDateField.html'}];
export const description = 'Allows users to enter and edit date and time values using a keyboard.';

# DateField

<PageDescription>{docs.exports.DateField.description}</PageDescription>

<ExampleSwitcher>
  <VisualExample
    component={VanillaDateField}
    docs={vanillaDocs.exports.DateField}
    links={vanillaDocs.links}
    props={['label', 'granularity', 'isDisabled']}
    initialProps={{label: 'Date'}}
    type="vanilla"
    files={["starters/docs/src/DateField.tsx", "starters/docs/src/DateField.css"]} />
  <VisualExample
    component={TailwindDateField}
    docs={vanillaDocs.exports.DateField}
    links={vanillaDocs.links}
    props={['label', 'granularity', 'isDisabled']}
    initialProps={{label: 'Date'}}
    type="tailwind"
    files={["starters/tailwind/src/DateField.tsx"]} />
</ExampleSwitcher>

## Value

Use the `value` or `defaultValue` prop to set the date value, using objects in the [@internationalized/date](internationalized/date/) package. This library supports parsing date strings in multiple formats, manipulation across international calendar systems, time zones, etc.

```tsx render
"use client";
import {parseDate, getLocalTimeZone} from '@internationalized/date';
import {useDateFormatter} from 'react-aria';
import {DateField} from 'vanilla-starter/DateField';
import {useState} from 'react';

function Example() {
  let [date, setDate] = useState(parseDate('2020-02-03'));
  let formatter = useDateFormatter({ dateStyle: 'full' });

  return (
    <>
      <DateField
        ///- begin highlight -///
        value={date}
        onChange={setDate} />
      {/*- end highlight -*/}
      <p>Selected date: {date ? formatter.format(date.toDate(getLocalTimeZone())) : '--'}</p>
    </>
  );
}
```

### Format options

The date format is automatically determined based on the user's locale. `DateField` supports several props to control how values are displayed.

```tsx render docs={docs.exports.DateField} links={docs.links} props={['granularity', 'hourCycle', 'hideTimeZone', 'shouldForceLeadingZeros']} initialProps={{label: 'Date'}}
"use client";
import {parseZonedDateTime} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';

<DateField
  /* PROPS */
  defaultValue={parseZonedDateTime('2025-02-03T08:45:00[America/Los_Angeles]')} />
```

### International calendars

By default, `DateField` displays the value using the calendar system for the user's locale. Use `<I18nProvider>` to override the calendar system by setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string). The `onChange` event always receives a date in the same calendar as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale.

```tsx render wide docs={docs.exports.I18nProvider} links={docs.links} props={['locale']} initialProps={{locale: 'hi-IN-u-ca-indian'}}
"use client";
import {I18nProvider} from 'react-aria-components';
import {parseZonedDateTime} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';

<I18nProvider/* PROPS */>
  <DateField defaultValue={parseZonedDateTime('2025-02-03T08:45:00[America/Los_Angeles]')} />
</I18nProvider>
```

## Forms

Use the `name` prop to submit the selected date to the server as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string. Set the `isRequired`, `minValue`, or `maxValue` props to validate the value, or implement custom client or server-side validation. See the [Forms](forms) guide to learn more.

```tsx render
"use client";
import {today, getLocalTimeZone} from '@internationalized/date';
import {DateField} from 'vanilla-starter/DateField';
import {Button} from 'vanilla-starter/Button';
import {Form} from 'vanilla-starter/Form';;

<Form>
  <DateField
    label="Appointment date"
    ///- begin highlight -///
    name="date"
    isRequired
    minValue={today(getLocalTimeZone())}
    ///- end highlight -///
  />
  <Button type="submit">Submit</Button>
</Form>
```

## API

<Anatomy />

```tsx links={{DateField: '#datefield', DateInput: '#dateinput', DateSegment: '#datesegment'}}
<DateField>
  <Label />
  <DateInput>
    {segment => <DateSegment segment={segment} />}
  </DateInput>
  <Text slot="description" />
  <FieldError />
</DateField>
```

### DateField

<PropTable component={docs.exports.DateField} links={docs.links} showDescription />

### DateInput

<PropTable component={docs.exports.DateInput} links={docs.links} showDescription />

### DateSegment

<PropTable component={docs.exports.DateSegment} links={docs.links} showDescription />
